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Abstract 

TIME  SERIES  (TS)  is  a  software  program  used  to  view  graphs  or 
tables  of  data  from  annual  time  series  databases.  It  operates  on 
IBM  or  compatible  personal  computers.  A  version  of  this  software 
is  distributed  as  PS&D  VIEW,  which  includes  annual  data  reported 
from  more  than  190  countries  or  regions  for  over  60  major 
agricultural  commodities.  The  TS  software  greatly  eases  the 
review  and  initial  analysis  of  this  and  other  large  PC  databases. 
Features  include  quick  access  to  scrolling  tables,  chart  plotting 
of  series,  trends/  projections,  and  profiles,  calculation  of 
summary  statistics,  and  data  file  exporting.  The  main  program  is 
accompanied  by  several  utilities  that  allow  users  to  build  and 
manipulate  annual  databases  for  use  in  the  TS  program.  This 
document  describes  the  capabilities  and  use  of  the  TS  program  and 
utilities . 
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TS  Software  User  Manual  for  the  TIME 
SERIES  Program  and  Utilities 

Alan  Webb,  Karl  Gudmunds,  and  Gene  Hasha 


Introduction 

The  development,  testing,  and  public  distribution  of  PS&D  VIEW: 
User ' s  Manual  and  Database1  has  demonstrated  the  value  of  user- 
friendly  software  for  viewing  tables  and  graphs  of  a  major  USDA 
database  on  a  personal  computer.  The  essential  characteristic  of 
the  PS&D  VIEW  software  is  that  its  operation  is  so  simple  and  so 
fast  that  most  people  can  conquer  its  principal  features  within  a 
few  minutes.  This  gives  users  instant  access  to  a  large 
comprehensive  database,  allowing  them  to  begin  to  formulate 
hypotheses  and  investigate  relationships  that  would  not  have  even 
been  considered  in  less  tractable  frameworks.  Thus,  the  PS&D 
VIEW  software  fills  a  niche  not  addressed  by  commercial 
spreadsheet  and  database  packages  that  must  sacrifice  simplicity 
and  speed  to  meet  the  more  general  requirements  of  a  diverse  set 
of  uses. 

The  success  of  PS&D  VIEW  has  led  to  demands  for  similar  software 
applicable  to  other  data.  In  response,  we  have  developed  a  data 
viewer  program  called  TIME  SERIES  (TS)  and  a  suite  of  TS  data 
utilities.  The  TIME  SERIES  program  provides  the  same 
capabilities  as  PS&D  VIEW  for  any  annual  time  series  data  and  the 
utilities  allow  data  file  manipulation.  One  TS  utility  allows 
conversion  of  structured  data  files  in  ASCII  format  into  TS  data 
files.  Other  utilities  permit  the  user  to  manipulate  existing  TS 
files  or  to  create  new  TS  data  files  from  components  of  other  TS 
files. 

The  software  capabilities  that  have  already  been  developed  are 
substantial,  even  though  the  development  of  the  TIME  SERIES 
program  and  utilities  is  incomplete  and  far  from  being  a 
comprehensive  data  viewing  and  manipulation  package.  Many  people 
within  ERS  are  already  using  the  system  for  organizing,  viewing, 
and  distributing  their  own  databases.  This  instruction  manual 
will  broaden  the  user  base  of  the  TIME  SERIES  program  and 
utilities  and,  we  hope,  facilitate  collaboration  with  others  on 
further  software  and  data  developments. 


1  Published  and  updated  annually  in  November  since  1989  by  Alan 
Webb  and  Karl  Gudmunds,  U.S.  Dept,  of  Agr.,  Econ.  Res.  Serv. 
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About  the  Manual 


This  manual  is  divided  into  two  sections.  The  first  is  a  quick 
overview  of  software  features  and  capabilities  of  the  TIME  SERIES 
program  itself.  We  keep  the  discussion  on  how  to  invoke  these 
features  to  a  minimum.  It  is  our  experience  that  most  users  do 
not  want  to  wade  through  detailed  documentation  before  using  a 
program,  particularly  when  most  procedures  are  self-evident  from 
the  menus.  We  provide  explanations  where  the  menu  selections  are 
less  obvious.  You  can  call  up  extensive  help  screens  by  pressing 
the  fi  key. 

The  manual's  second  section  contains  information  on  how  to  use 
the  TIME  SERIES  utilities  for  creating  and  manipulating  TS  data 
files.  Users  will  find  some  of  these  utilities  less  tractable 
than  the  TIME  SERIES  program  itself.  There  are  two  reasons  for 
this.  First,  we  have  essentially  taken  the  programs  to  create 
and  manipulate  the  standard  USDA  supply-utilization  files  and 
made  modifications  so  that  the  utilities  would  be  more  generic. 
Thus,  the  utilities  work  best  on  data  files  with  a  structure 
similar  to  the  annual  commodity-country-balance  sheet  structure 
of  the  PS&D  data.  Their  application  to  other  types  of  database 
structures  may  not  work  as  well.  Second,  the  use  of  the  TIME 
SERIES  utilities  has  not  been  as  widespread  as  the  PS&D  VIEW 
program  and,  consequently,  we  have  not  had  the  level  of  user 
feedback  that  we  need  to  refine  these  programs.  A  key  objective 
in  publishing  this  manual  is  to  encourage  the  use  of  the 
utilities  and  stimulate  suggestions  for  further  developments. 

You  will  find  the  following  typographic  conventions  throughout 
this  manual. 

Type  style 

italic 

bold 


ALL  CAPITALS 


SMALL  CAPITALS 


Initial  Capitals 
KEY1+KEY2 


► 


Used  for 

Anything  you  must  type  exactly  as  it  appears. 

Placeholders  for  information  you  must 
provide.  If  you  are  asked  to  type  FILENAME, 
you  would  type  the  actual  name  of  the  file. 

Program  names,  file  names,  directories,  and 
acronyms . 

The  names  of  keys  on  your  keyboard.  For 
example,  enter  or  esc. 

Menu  items  and  labels. 

A  plus  sign  (  +  )  between  key  names  means  press 
and  hold  down  the  first  key,  then  press  the 
second  key. 

Denotes  alternative  choices  available  at  a 
particular  point  in  the  program. 
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Program  Setup 

Before  running  TS,  you  must  install  the  software  and  some  data 
files  on  your  PC  hard  disk.  See  the  README.DOC  file  on  the 
installation  disk  for  instructions.  Type  READ  at  the  floppy  disk 
drive  prompt  to  view  this  file.  Any  last-minute  information  not 
included  in  this  manual  can  also  be  found  in  the  README.DOC  file. 

The  TS  software  requires  an  IBM  or  compatible  PC  with  a  hard 
disk,  MS-DOS  or  PC-DOS  3.0  or  greater,  300  kilobytes  (KB)  of 
available  RAM,  and  graphics  capability.  A  math  co-processor  will 
speed  calculations,  but  is  not  required.  Graphics  support  is 
provided  for  all  common  graphics  hardware  (VGA,  EGA,  MCGA ,  CGA , 
and  Hercules  monochrome) .  TS  will  print  graphs  on  Epson  dot 
matrix  and  Hewlett-Packard  laser  printers,  and  compatibles.  To 
use  printers  not  supported  by  TS,  users  can  enable  their  own 
graphics  printing  utility  before  starting  TS.  One  such  utility 
is  GRAPHICS.COM  in  DOS  2.0  or  later  releases. 

Files  in  the  TS  Package 


Program  Files 

TS.EXE 
TS.OVR 
TS.HLP 
READ . EXE 
FV.COM 

Utility  Files 

OPEN . BAT 
OPENALL . BAT 
COMPRESS . BAT 
COMP ALL . BAT 
LHARC.EXE 
LHARC . MAN 
TSSHELL.EXE 


TSSHELL.CMD 

ADDYEARS . EXE 

DRIVES . EXE 

MAP. EXE 

PRINTPCX.EXE 

PRN2TS.EXE 

READ . EXE 

SPECS . EXE 

TS2DBASE.EXE 

TS2DBF.EXE 

TS2MNU.EXE 

TS2PRN.EXE 

TS2WK1.EXE 

TSADD.EXE 

TSADJYR.EXE 


TSBLOCK.EXE 

TSCOLUMN.EXE 

TSC0PY.EXE 

TSC0PYNM.EXE 

TSC0PYC.EXE 

TSEDIT.EXE 

TSFILE.EXE 

TSHELP.EXE 

TSJOIN.EXE 

TSSCALAR.EXE 

TSSUB.EXE 

TSSUBSET.EXE 

TSTABLES.EXE 

TSTRIM.EXE 

TSUPDATE.EXE 

WKS2PRN.EXE 


Your  TS  installation  disks  will  have  a  miscellaneous  collection 
of  data  files,  depending  on  data  revisions  and  availability. 

All  TS  software  files  are  in  the  public  domain  and  may  be  freely 
distributed.  TS  data  released  by  ERS  is  public  information.  ERS 
can  provide  only  very  limited  support  to  non-ERS  users  of  the 
package,  and  cannot  support  users  who  modify  the  software  or  data 
files.  ERS  disclaims  all  warranties  of  fitness  for  a  particular 
use. 


The  TIME  SERIES  Program 


Speed  and  ease  of  use  have  made  TS  popular  within  the  USDA's 
Economic  Research  Service.  Even  novice  computer  users  can 


3 


effectively  use  TS.  No  spreadsheet,  graphics,  or  database 
program  is  required.  Everything  is  menu-driven.  The  software 
allows  the  user  to  browse  through  graphs  or  tables  of  data,  plot 
multiple-line  graphs,  fit  trend  lines,  print  graphs  and  tables, 
and  export  data  for  use  in  other  programs. 

Starting  TS 

To  start  TS,  type  TS  and  press  enter.  A  title  screen  will  be 
displayed,  followed  by  a  menu  of  the  data  files  available  (fig. 

1)  • 

►  Use  the  cursor  keys  to  highlight  the  file  to  view,  and  press 
enter  to  select  it.  Files  are  shown  with  the  date  of  their 
last  revision. 

►  You  can  also  highlight  your  choice  by  typing  the  first  letters 
of  its  name.  The  current  search  string  will  appear  in  the 
lower  left  corner  of  the  list. 

►  Each  of  the  USDA  production-supply-distribution  (PS&D)  files 
contain  country  balance  sheets  for  a  single  commodity.  Other 
TS  data  files  may  contain  a  variety  of  annual  data. 

Menus  and  Help 

Once  you  have  made  a  file  selection,  the  main  menu  will  appear 
with  four  headings:  Data,  Graph,  Table,  and  Program. 

►  You  will  see  context-sensitive  help  displayed  at  the  bottom  of 
each  screen;  extensive  help  is  available  at  the  press  of  the  fi 
key.  Press  fi  twice  for  a  list  of  help  topics. 


Figure  1.  The  File  Selection  menu 
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Figure  2 .  The 

Main  menu 

—  TlMfi  Series  ===== 

Data 

=  USDA  Economic 

Graph 

Research  Service  =■= 

Table 

=  BARLEY.  TS  == 

Program 

►  You  make  all  selections  from  menus  and  prompts  or  by  pressing 
the  following  action  keys,  which  are  active  at  almost  every 
screen. 


Key: 

Action: 

FI 

Help: 

This  displays  context-sensitive  help  text. 

ALT+N 

Notes : 
current 
You  can 
while  a 

Displays  text  notes  associated  with  the 
data  file,  if  the  text  file  is  available, 
edit  this  text.  Notes  will  not  pop  up 
graph  is  displayed. 

ESC 

Escape : 
choice 

This  backs  you  out  of  the  current  menu 
or  exits  the  current  graph. 

ALT+X,  ALT+Q 

Quit: 

This  exits  the  TS  program  immediately. 

The  Data  Menu 

In  the  Data  menu,  you  make  the  choices  necessary  to  display  a 

data  series. 

►  Select  a  data  series  by  choosing  the  name  of  a  table  and 
column  from  scrolling  menus  (fig.  3) .  The  two  entries 
directly  under  the  Data  heading  will  differ  in  name,  depending 
upon  the 
file 

loaded,  but 
they  act 
the  same 
for  all 
files.  The 
first  entry 
pops  up  a 
list  of 
table  names 
and  the 
second 
entry  pops 
up  a  list 
of  column 
names . 

►  If  you  type 
the  first 
letters  of 
a  name,  the 


Figure  3.  Making  a  choice  from  the  Data  menu 
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Data  Graph  Table  Program 
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menu  selection  bar  will  jump  to  the  matching  name.  Type  NEW, 
for  example,  to  skip  to  New  Zealand  (if  it  is  available) . 
Press  enter  to  select  the  highlighted  name. 


The  Graph  Menu 

Choices  from  the  Graph  menu  (fig.  4)  change  the  data  series  shown 
and  its  display.  Other  choices  are  available  through  hot  keys 
while  a  graph  is  on  screen. 

Display 

►  Choose  Display  from  the  Graph  menu  to  show  a 
plot  of  the  data  selected.  Figure  5  shows  a 
simple  line  plot. 

►  The  other  Graph  menu  choices  alter  the 
features  of  the  graph.  First  we  will  look  at 
the  options  available  when  a  graph  is 
displayed  on  screen. 


Figure  4 .  The 
Graph  menu 


Graph 

Display 
Trend  Line 
Limits 

Style 

Uieupoint 

Figure  5.  The  Graph/Display  choice  plots  a 
series 

WORLD  Barley  Area  Harvested 

in  Ten  mil  ions 


Year 

S  92.03.10 _ fv  in-n-i9<i 


Graph  Action  Keys 

You  have  several  options  when  a  graph  is  displayed: 

►  Press  esc  to  exit  the  graph  and  return  to  the  main  menu. 
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►  Press  Fl  for  help  on  the  graph  action 
keys  (fig.  6) .  The  help  box  lists  the 
choices  available  while  a  graph  is  on  the 
screen.  You  must  exit  the  help  box 
before  making  a  selection. 

►  Arrow  and  page  keys  (ti  PageUp  PageDown) 
will  change  the  series  displayed. 

►  The  plus  key  (+)  lets  you  add  up  to  three 
other  series  to  the  one  displayed.  The 
minus  key  (-)  removes  a  series. 

►  Press  a  to  display  a  table  of  the  axis  data  with  statistics. 
Press  t  to  show  a  table  of  the  fitted  trend  data,  the  residuals 
and  fit  statistics  (if  a  trend  line  is  selected,  see  below) . 

►  The  ins  key  permits  you  to  insert  text  directly  on  the  graph. 
While  inserting  text,  press  Fl  for  help  on  your  text  options. 

►  Press  p  to  print  a  graph.  A  menu  of  printer  choices  will 
appear.  You  can  then  select  a  choice  to  begin  printing. 

►  Press  s  to  save  a  graph  for  later  printing  or  viewing.  The 
graph  image  will  be  saved  in  the  common  PCX  bitmapformat .  You 
can  use  the  PRINTPCX  program  (see  page  15)  to  later  view  or 
print  multiple  images.  PRINTPCX  will  also  let  you  convert 
color  PCX  images  into  black  and  white  images  suitable  for 
inclusion  in  a  word-processing  document. 

Trend  Line 

►  Fit  a  trend  line  to  a  data  series  simply 
by  selecting  the  functional  form  from  the 
Graph/  Trend  Line  menu  (fig.  7) . 

►  Refer  to  Help  (fi)  for  further 
information  or  press  t  at  the  graph 
display  for  a  table  of  results. 

Limits 


►  The  Limits  choice  allows  you  to  change 

the  span  of  the  time  series  plotted,  the  span  of  the  trend 
line  fit,  the  display  of  projection  results,  or  all  of  these. 
If  a  series  or  trend  includes  projected  values,  a  vertical 
white  line  marks  the  last  year  of  historical  data.  Figure  8 
shows  a  two-series  plot  with  trend  lines  and  projection  year 
limits . 

Style 

►  The  Style  choice  permits  you  to  choose  line,  bar,  or  scatter 
displays.  Only  bars  will  display  if  a  profile  is  selected 
(see  Viewpoint  below) . 


Figure  7. 

Trend  line  choices 


Graph 


Display 
Trend  Line 
Lini 
Sty  1 
View 


No  Trend  Line* 
Line 

Parabola 
Exponential 
Fit  The  Best 


Figure  6 . 

Graph  screen  help 


Uar iables 

t* 

Count  r ies 

Paget* 

New  1 ine 

♦  - 

Axis  data 

A 

Trend  data 

T 

Insert  text 

I  ns 

Print  graph 

p 

Save  graph 

s 

Ex i t  graph 

Esc 

Exit  Help 

Any  keg 
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Viewpoint 


►  Choose  Viewpoint  if  you 
want  to  change  from  a 
time  series  display  to  a 
profile  display  of 
either  table  or  column 
names  for  a  given  year. 

►  The  Viewpoint  menu 
example  (fig.  9)  shows 
the  selection  of  a 
European  country  profile 
from  selected  tables. 

►  After  selecting  Display 
from  the  Graph  menu,  the 
profile  is  drawn.  See 
figure  10. 


Figure  8.  Multi-line  trend  projections 


►  For  a  Tables  Profile 
(profile  of  data  across 
tables) ,  you  can  either 
choose  the  tables  to  be 
displayed  or  you  can  let 
TS  select  the  top 
members  and  array  them 
in  order.  A  limit  of  50 
items  can  appear  in  a 
profile.  The  name  of 
the  Tables  Profile  and 
Columns  Profile  options 
will  differ  depending  on 
the  contents  of  the  TS 
file  loaded. 


Figure  9.  Viewpoint  menu  example 


►  The  initial  profile 
display  is  for  the  last 
year  of  historical  data. 
Change  the  year  by  using 
the  page  keys  (PageUp 
PageDown)  .  Press  Fl  for 
help. 

►  By  using  the  Top  Members 
option  you  can  quickly 
plot  a  sorted  list  of 
data  items.  Figure  11 
shows  an  example. 


Figure  10.  A  plot  of  selected  values 
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Figure  11.  A  plot  of  sorted  values 


Barley  Area  Harvested  for  1001 


In  UnTLlU. 


The  Table  Menu 

The  Table  menu  (fig.  12) 
allows  you  to  look  at  data 
in  tabular  format  and  to 
define  subset  tables  that 
can  be  saved  and  imported 
into  other  software 
packages . 

Browse  Data 

►  Choose  this  option  to 
view  individual  data 
tables  from  the  current 
file. 


►  When  viewing  tables,  a 
help  bar  appears  at  the 

bottom  of  the  screen.  Use  the  page  keys  (PageUp 
PageDown)  to  change  the  table  displayed  or  press 
Ait+T  to  pick  from  a  list  of  tables.  Use  the 
arrow  keys  (Ti*-»)  to  scroll  the  columns  and 
rows.  You  can  jump  directly  from  a  table  to  a 
graph,  or  to  axis  and  trend  data.  Press  fi  for 
help  on  other  choices. 

Create  Tables 

►  When  you  choose  Create  Tables,  you  jump  into 
another  set  of  menus  (fig.  13) . 


CMM-EV  10-17-11*1 


Figure  12 . 

Table  menu 


Table 


Browse  Data 
Create  Tables 
Axis  Data 
Trend  Data 


►  Use  the  choices  under  Data  to  select  the  tables  and  columns 
you  want  to  view  or  save.  You  must  mark  choices  with  the  + 
key.  Choose  Reset  Marks 
to  quickly  undo  all  of 
your  selections. 


►  Use  the  Export  options 
(fig.  14)  to  arrange  the 
data,  view  it,  save  it, 
or  print  it. 

View  -  displays  a 
temporary  text  file  of  the 
data  selected.  It  is  a 
convenient  way  to  view  a 
subset  of  the  tables  and 
columns  in  a  TS  file. 

This  also  can  be  used  to 
see  the  effects  of  Orientation  or  Layout  selections  before  using 
the  Save  or  Print  option. 


Figure  13 .  The  Create  Tables  menus 


Create  a  Table 

Export 


Count  r  1m 
Variables 
Reset  Marks 
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Area  Harvested 
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Inparts 
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Std  Exp  (Oct-Sep) 


:  ■  i 


iiifuihomin  uiifl'HiUfiiiiiiiii:!  t  m  i  ti  i  i  wIihii 

rk  choices,  <En+or>  to  continue,  <Esc>  to  cancel. 

PI  =  Help  . —■■■■■  — 
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Save  -  pops  up  a  list  of  file  formats  to  let  you 
save  your  data  choices  to  a  file.  You  will  be 
prompted  for  a  file  name.  If  you  need  to  export 
TS  data  for  use  by  other  software,  use  this  menu 
item.  The  WK1  and  DBF  file  format  selections  are 
not  affected  by  the  Orientation  or  Layout  options 
(see  below) . 

Print  -  prints  your  current  table  and  column 
selections.  Many  printers  cannot  print  more  than 
five  columns  of  TS  data.  Use  View  to  check  the 
table  width  before  printing. 


Figure  14. 

Export  menu 


Create  a  Table 
Export 

U  iew 

Save 

Print 

Or  ientat ion 
LayOut 

Orientation  -  lets  you  array  data  tables  side  by  side.  The 
default  is  one  above  the  other. 


Layout  -  lets  you  array  years  across  rows  or  down  columns.  The 
default  is  down  columns. 


►  Go  to  the  Return  option  to  get  back  to  the  main  TS  menu  or  to 
clear  your  selections  and  create  more  tables. 


Axis  Data 


►  This  table  option  (fig.  15)  at  the  main  menu 
displays  the  latest  data  series  selected, 
including  summary  statistics.  This  is  the 
series  used  to  plot  a  graph.  To  change  the 
series,  you  must  make  a  new  choice  from  the 
Data  menu. 

►  The  Axis  Data  screen  can  also  be  displayed 
while  at  a  graph  by  pressing  the  letter  a.  If 
more  than  one  series  has  been  plotted,  only  the 
last  series  is  shown.  The  range  of  years  used 
for  the  series  and  statistics  can  be  adjusted 
through  the  Graph/Limits  options. 


Figure  15. 

Table  menu 


Table 

Brouse  Data 
Create  Tables 
Axis  Data 

Trend  Data 

►  Table  or  column  profile  lists  and  statistics  are  shown  if  a 
Graph/Viewpoint  profile  is  chosen.  You  can  quickly  see  a  list 
of  the  tables  with  the  greatest  values  (for  example,  countries 
with  the  highest  commodity  consumption)  by  choosing  a  table 
profile  from  Graph/Viewpoint  and  selecting  the  Top  Members 
option.  Then  select  Table/Axis  Data  to  view  the  list  or 
Graph/Display  to  plot  a  chart. 


Trend  Data 


►  If  a  Graph/Trend  Line  has  been  selected  for  a  time  trend,  then 
the  values  composing  the  trend  can  be  displayed  with  the  Trend 
Data  option  (fig.  15) .  Summary  statistics  for  the  original 
series  and  for  the  trend  are  included,  as  well  as  residual 
values  (trend  minus  original) .  The  list  scrolls  with  the 
arrow  keys,  and  you  can  toggle  between  the  axis  and  trend  data 
with  the  a  and  t  keys. 
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The  Program  Menu 


The  Program  menu  (fig.  16)  contains  an 
assortment  of  functions.  These  provide  help  on 
the  program  or  the  data,  load  new  files,  change 
the  units  displayed,  jump  to  DOS,  or  exit  the 
program. 

Help 

►  The  Help  choice  invokes  the  same  Help  screens 
as  are  available  by  pressing  the  fi  key  at  any 
of  the  menu  screens. 

File 


Figure  16. 

Program  menu 


Program 

Help  (FI) 
File 

Notes 

Units 

Scalar 

Go  to  DOS 
Quit 

►  File  lets  you  select  another  data  file  from  a  menu.  You  can 
select  files  located  in  other  directories  or  drives.  Loading 
in  a  new  file  will  return  TS  to  its  defaults  (time  trend,  no 
trend  line,  no  user-specified  units  or  scalar) .  Only  one  file 
can  be  loaded  at  a  time. 


Notes 


►  Choose  Notes  to  read  or  edit  text  information  on  the  current 
data  file.  You  also  can  pull  up  the  Notes  box  by  pressing 
alt+n  at  any  of  the  menus. 

Units 


►  The  Units  choice  allows  you  to  change  the  units  displayed. 
Choices  are  the  default  magnitude,  an  index  based  on  the  value 
for  a  given  year,  and  user  magnitudes.  If  "WORLD"  is  the 
first  table,  then  a  share  of  the  world's  value  choice  is  also 
available.  This  option  affects  both  graphs  and  tables.  The 
default  magnitude  for  most  TS  data  files  is  1,000;  that  is, 
the  value  seen  in  a  table  is  in  thousands. 

Scalar 


►  Scalar  lets  you  multiply  all  displayed  values  by  a  user- 
selected  scalar.  This  function  is  useful  for  converting  units 
of  measure  (for  example,  changing  metric  tons  to  bushels) . 

Note  that  all  series  will  be  multiplied  by  the  same  conversion 
factor.  This  can  lead  to  incorrect  values  for  series  with 
different  units  of  measure  (that  is,  the  value  used  in 
converting  metric  tons  to  bushels  will  also  be  used  on  series 
that  originally  may  not  have  been  in  metric  tons) . 

►  The  scalar  can  range  from  0  to  1,000;  if  it  is  any  value 
besides  1,  you  will  be  prompted  for  the  new  unit  label. 
Remember  that  the  default  is  usually  1,000.  Most  series  in 
the  PS&D  data  files  are  in  1,000  metric  tons. 
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DOS  Shell 


►  The  DOS  Shell  choice  returns  you  to  the  DOS  prompt 
temporarily,  but  keeps  TS  in  memory.  This  is  not  the  normal 
way  to  exit  the  program.  It  is  useful  if  you  need  to  execute 
a  DOS  command  and  would  like  to  return  to  the  same  data  file. 
The  data  file  itself  is  dropped  from  memory  and  reloaded  upon 
return,  so  default  values  will  be  in  effect  (see  File  above) . 

Quit 

►  This  exits  the  TS  program.  You  also  can  exit  the  program  from 
almost  any  screen  by  pressing  alt+x  or  alt+q. 


The  TIME  SERIES  Utilities 

There  are  currently  over  two  dozen  TIME  SERIES  utilities  (see 
page  37) .  The  TS  utilities  let  you  exchange  data  between  TS 
files  and  other  files,  manipulate  the  data  in  a  TS  file,  or 
create  new  TS  files  from  data  in  one  or  more  existing  TS  files. 

The  interactive  programs  -  those  that  prompt  the  user  for 
keyboard  input  and  execute  based  on  the  user's  response  -  are 
marked  with  an  double-headed  arrow  («■)  in  the  tables.  The 
unmarked  programs  are  batch  programs,  that  is,  they  execute  based 
on  instructions  provided  by  the  user  at  the  time  the  program  is 
started.  For  all  the  batch  programs,  you  can  type  the  name  of 
the  program  to  obtain  instructions  on  how  it  works  and  what 
information  it  needs  as  input.  The  distinction  between 
interactive  and  batch  is  important  because  it  provides  a  rough 
delineation  between  one-time  single-user  manipulations,  which  are 
best  done  interactively,  and  repeated  data  maintenance  and  data 
file-building  tasks,  which  are  carried  out  more  easily  in  batch 
mode . 

The  discussion  of  the  TIME  SERIES  utilities  is  divided  into  four 
sections  corresponding  to  four  sets  of  applications.  Each 
section  contains  a  table  listing  relevant  TS  utilities,  followed 
by  descriptions  of  their  purpose  and  use.  The  first  section 
reviews  the  utilities  used  in  general  support  of  the  TS  program 
and  the  suite  of  utilities.  The  second  section  discusses  file 
conversion  utilities  to  move  data  into  and  out  of  TS  data  files. 
The  third  section  discusses  the  utilities  used  to  manipulate  or 
change  the  data  within  a  single  existing  TS  data  file.  The  last 
section  covers  the  utilities  used  to  create  a  new  TS  data  file 
from  two  or  more  existing  TS  data  files. 

Sophisticated  data  manipulations  or  queries  should  be  done  in  a 
database  management  or  spreadsheet  program.  You  can  then  convert 
the  output  values  from  these  software  packages  to  TS  files  for 
easy  viewing. 
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There  are  three  key  features  of  the  TIME  SERIES  program  itself 
(TS.EXE)  that  are  particularly  relevant  to  the  creation  and 
manipulation  of  new  TS  data  files:  file  notes,  creating  tables, 
and  compressed  files. 

File  Notes 

Within  TIME  SERIES,  you  can  type  alt+n  or  select  Notes  from  the 
Program  menu  to  display  text  information  pertinent  to  the  current 
TS  file.  As  long  as  the  TS  data  files  created  are  for  the  use  of 
a  limited  number  of  people,  most  users  will  not  bother  to  add 
this  information.  For  more  widely  distributed  TS  files,  adequate 
documentation  is  essential  to  prevent  the  misuse  and 
misinterpretation  of  data.  This  documentation  is  easy  to 
incorporate.  Create  an  ASCII  text  file  with  the  information  you 
wish  to  provide  and  give  the  text  file  the  same  name  as  the  TS 
data  file,  but  with  a  DOC  extension.  For  example,  WHEAT . DOC 
would  be  the  documentation  file  for  a  WHEAT. TS  or  WHEAT. TSC  file 
and  the  information  in  it  could  be  accessed  on  screen  from  the 
TIME  SERIES  program  by  pressing  alt+n  when  the  WHEAT. TS  file  is 
loaded . 

Create  Table  Function 

You  can  output  a  subset  of  the  data  already  in  a  TS  data  file  to 
a  spreadsheet-readable  file  with  the  Create  Table  function  in 
TIME  SERIES  and  TSTABLES  (see  page  21) .  This  can  be  a  useful 
starting  point  for  building  a  PRN  file  for  use  with  the  PRN2TS 
utility.  For  most  purposes,  however,  other  TS  utilities  will 
perform  the  desired  manipulation (s)  faster  with  less  chance  of 
user  error.  The  TS  utilities  handle  only  common  manipulations  of 
data.  When  other  manipulations  of  data  are  needed,  the  user  must 
resort  to  a  more  fundamental  method:  the  creation  of  a  TS  data 
file  from  an  ASCII  text  file  (from  spreadsheet  or  database 
management  program  output)  and  a  text  file  of  instructions  for 
the  PRN2TS  utility. 

Compressed  Data  Files  (TSC  Files) 

TS  data  files  with  an  extension  of  .TSC  are  compressed  data  files 
created  with  a  file  compression  utility  (two  of  the  more  popular 
such  utilities  are  PKZIP  and  LHARC) .  This  is  done  solely  to 
conserve  disk  space.  These  files  are  self-extracting  archives  of 
the  data.  An  archive  file  must  be  opened  before  it  is  used  by 
the  TS  program  (TS.EXE)  or  any  of  the  TS  utilities.  This  opening 
process  is  done  automatically  when  you  select  a  TSC  file  in  the 
TS  program,  but  you  must  do  it  manually  if  you  want  to  use  the  TS 
utilities  upon  a  TSC  file.  You  also  may  prefer  to  keep 
uncompressed  TS  files  to  save  time  in  loading  data  when  running 
the  TS  program.  This  comes  at  the  cost  of  disk  space.  See  the 
Compressed  Data  Files  section  (page  34)  for  more  information. 
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Table  1 —  General  support  utilities 


File  name 

Description  of  function 

TSSHELL.EXE^ 

A  menu  shell  with  descriptions  and  syntax 
instructions  for  all  of  the  TS  utilities. 
With  TSSHELL,  you  can  scroll  through  a 
list  of  the  TS  utilities  and  run  the  one 
you  want.  This  is  a  good  entry  point  into 
the  suite  of  TS  software. 

READ. EXE^ 

A  utility  for  reading  DOS  text  (ASCII) 
files.  This  is  used  by  the  TIME  SERIES 
main  program  and  the  TSTABLES  utility  to 
view  user-created  tables. 

PRINTPCX. EXE~ 

A  program  to  print  graphs  saved  in  PCX 
format  by  TIME  SERIES. 

TSHELP .  EXE++ 

A  hyper-text  guide  to  the  TS  utilities, 
useful  for  selecting  the  correct  utility 
for  the  task  you  have  in  mind. 

SPECS.EXE  and 

MAP. EXE 

Utilities  to  check  computer  hardware, 
settings,  and  memory  use.  These  are 
useful  for  trouble-shooting. 

DRIVES . EXE 

Lists  the  disk  drives  present  on  the 
computer  and  the  free  space  available  on 
each.  This  is  useful  in  selecting  a  drive 
for  software  and  data  installation. 

General  Support  Utilities 

There  are  only  a  few  programs  you  need  to  know  about  to  start 
using  the  TS  software.  These  are  listed  in  table  1.  The 
TSSHELL.EXE  utility  lets  you  browse  through  and  run  any  of  the  TS 
software  programs,  including  the  core  TS.EXE  program  described  in 
the  first  part  of  this  document.  Most  of  the  TS  utilities  run 
much  faster  if  your  PC  has  a  math  co-processor.  You  can  run  the 
SPECS  utility  (page  16)  to  check  if  one  is  present  in  your  PC. 

TSSHELL.EXE 


A  menu-driven  interactive  utility  that  combines  the  features  of 
all  the  TS  utilities  is  a  long-run  objective  of  this  development 
process.  The  TSSHELL  utility  is  a  first  step  in  this  direction. 
The  version  documented  here  is  merely  a  menu  shell  with  program 
descriptions  and  instructions  for  all  the  TS  utilities. 

To  activate  the  menu  shell,  type  TSSHELL  from  within  the 
subdirectory  which  contains  the  TSSHELL.EXE  program,  the 
TSSHELL. CMD  file  and  the  TS  utilities.  Use  the  menu  descriptions 
to  decide  which  utility  will  perform  the  task  you  want  and  to 
execute  that  program. 
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READ . EXE 


The  READ  utility  lets  you  scroll  text  or  documentation  files  such 
as  README . DOC .  TS  requires  it  to  view  a  user-created  table. 

Just  type  READ  followed  by  the  full  name  of  the  text  file  to 
view.  If  no  file  name  is  given  and  a  README . DOC  file  is  found, 
then  README . DOC  will  be  displayed.  READ.EXE  can  handle  very  wide 
text  files  up  to  5,000  lines  long,  depending  upon  available  RAM. 

PRINTPCX.EXE 


This  program  lets  you  print,  display,  and  change  the  colors  of 
graphs  saved  by  the  TS  program.  Saving  graphs  in  TS  for  later 
printing  by  PRINTPCX  is  more  convenient  than  waiting  for  TS  to 
finish  printing  a  graph  before  getting  back  to  work.  Change  to 
the  directory  containing  your  saved  PCX  files  (they  will  have  a 
PCX  file  name  extension) ,  and  type  PRINTPCX. 

To  view  or  print  a  TS  graph,  use  the  arrow  keys  ( 1 1 )  to  highlight 
the  file  name.  Press  enter  to  view  the  graph,  and  esc  to  quit 
viewing.  PRINTPCX  also  allows  you  to  view  or  print  many  graph 
images  at  a  time.  If  you  mark  a  set  of  graphs  with  the  plus  key 
(+)  and  press  enter,  PRINTPCX  works  like  a  slide  show  presenting 
each  graph  image  on  the  screen  for  5  seconds.  Press  pause  to 
keep  an  image  on  screen.  Likewise,  if  several  graphs  are  marked 
using  the  plus  key  they  can  all  be  printed  by  pressing  FI.  Use 
the  F2  function  key  to  toggle  between  printer  choices.  Only  HP 
compatible  laser  printers  and  Epson  compatible  dot-matrix 
printers  are  supported. 

The  Drain  Colors  choice  (F3)  converts  a  PCX  image  saved  on  a 
color  monitor  to  a  black  and  white  image  that  may  be  more 
appropriate  for  importing  into  a  word  processing  document.  Once 
colors  are  drained  they  cannot  be  replaced. 


Figure  17. 


The  PrintPCX  utility  menu 
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FI  =  Print  F2  =  Printer  (HP  LaserJet,  Landscape)  F3  =  Drain  Colors 
F4  =  Reverse  Colors  F5  =  Type  Text  F10  =  Delete? lie 
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The  Reverse  Colors  option  (F4)  is  useful  for  changing  a  PCX  image 
for  use  in  a  word  processing  document  or  desktop  publishing  file. 
This  selection  will  turn  the  black  background  of  a  graph  white. 

If  you  want  to  import  an  image  into  a  word  processor  such  as 
WordPerfect,  you  would  use  F3  followed  by  F4.  Any  Reverse  Colors 
changes  made  can  be  reversed  by  pressing  F4  again. 

The  Type  Text  option  (F5)  lets  you  annotate  a  graph  with  large  or 
small  text  in  either  horizontal  or  vertical  orientation.  It 
works  just  as  in  TS,  and  help  is  available  with  fi  when  you  are 
in  Type  Text  mode. 

TSHELP.EXE 


The  TSHELP  utility  provides  a  function-oriented  guide  to  the 
selection  of  an  appropriate  TS  utility  for  the  task  at  hand. 

Just  type  TSHELP  to  start  the  program.  Use  the  arrow  or  tab  keys 
to  move  between  the  highlighted  topics,  and  press  ENTER  to  jump 
to  a  topic.  To  quit,  press  ESC. 

SPECS . EXE ,  MAP. EXE.  DRIVES . EXE 

These  are  simple  utilities  to  check  computer  hardware  and  memory 
use.  These  are  useful  for  trouble-shooting  or  displaying  basic 
information  about  the  status  and  setup  of  your  PC.  SPECS  will 
give  a  summary  of  system  components,  memory  configuration,  and 
drive  status;  MAP  will  show  a  listing  of  programs  loaded  in 
conventional  DOS  memory;  DRIVES  will  list  the  drives  available  on 
your  PC,  their  size,  and  available  space. 

File  Conversion  Utilities 

Data  in  the  TIME  SERIES  program  are  easy  to  view  and  analyze 
because  they  have  been  assembled  in  a  well-structured  format  that 
allows  the  program  to  find  and  display  the  appropriate  series 
based  on  menu  choices.  The  USDA  PS&D  commodity  data  fit  this 
criteria  because  each  of  the  country  tables  in  the  PS&D  commodity 
files  has  been  set  up  with  the  same  column  and  row  headings. 

Many  other  data  sets  can  be  organized  along  the  same  lines  for 
incorporation  into  the  TS  software.  A  few  guidelines  should  be 
followed,  however,  to  ensure  that  the  organization  of  the  data 
best  meets  the  objectives  of  the  user. 

►  TS  is  designed  for  viewing  annual  time  series  numeric  data. 

If  your  database  does  not  contain  annual  data  or  contains  only 
a  limited  number  of  years  of  annual  data  (less  than  10  years, 
for  example) ,  then  the  TS  program  will  be  of  limited  use. 

►  All  or  most  of  the  data  in  a  file  should  be  in  the  same  units 
(for  example,  thousand  metric  tons  or  millions  of  dollars)  to 
facilitate  graphical  comparisons  of  data  series.  If  a  data 
set  contains  series  in  a  number  of  different  units,  it  might 
be  better  to  build  TS  data  files  from  subsets  with  similar 
units . 
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►  An  organized  data  set  is  just  numbers  organized  in  a 
multidimensional  space.  The  PS&D  data,  for  example,  have  a 
year,  variable,  country,  and  commodity  dimension.  TS  imposes 
a  hierarchy  on  these  data  set  dimensions.  The  first  and  most 
important  dimension  is  the  annual  time  series  because  the 
default  graphical  display  of  the  TS  program  is  as  a  trend  over 
time.  The  analyst  must  define  the  second  and  third  most 
important  dimensions  based  on  which  comparisons  are  most 
useful  to  the  user(s)  of  the  data.  When  you  create  a  new  TS 
data  file  using  the  procedures  described  below,  make  the 
second  and  third  most  important  dimensions  of  the  data  set  the 
column  and  table  headings,  respectively.  For  the  PS&D  TS 
files,  the  data  are  organized  by  commodity  file  to  facilitate 
within-country  and  cross-country  comparisons  within  a 
commodity  market.  Cross-commodity  comparisons  of  data  series 
are  not  possible  with  the  single-commodity  PS&D  files  because 
the  TIME  SERIES  program  cannot  access  information  in  separate 
files  simultaneously.  Multi-commodity  files  can  be  built  from 
single-commodity  files  by  using  the  TS  utilities,  however. 

►  If  a  data  set  already  exists  in  a  well-organized  format  but 
the  hierarchy  of  the  data  dimensions  is  not  appropriate  for 
the  intended  use,  it  may  be  easier  to  first  incorporate  the 
data  into  TS  and  then  use  some  of  the  TS  utilities,  discussed 
below,  to  reorganize  it. 


Several  TS  utilities  help  transfer  data  between  TS  files  and 
other  common  file  formats  (table  2) .  If  you  locate  data  in  TS 
files  that  you  want  to  use  in  other  applications,  you  can  export 
the  data  easily  with  these  utilities.  Likewise,  if  you  have  data 
in  a  text,  spreadsheet,  or  database  file,  you  can  create  a  TS 
data  file  from  your  data  with  these  utilities. 


Table  2 —  File  conversion  utilities 


File  name 
PRN2TS.EXE 
* . PRN/ * . MNU 

WKS2PRN.EXE 

TS2MNU.EXE 

TS2PRN.EXE 

TS2WK1.EXE 

TS2DBASE.EXE 

TS2DBF.EXE 
TSTABLES . EXE~ 


Description  of  function 

Creates  a  TS  binary  file  from  data  in  an 

ASCII  text  (PRN)  file.  The  utility  uses  a 
text  configuration  file  with  a  MNU 
extension  for  instructions. 

Dumps  the  labels  and  values  from  a 
spreadsheet  file  to  a  text  file. 

Creates  the  MNU  configuration  file  for  an 
existing  TS  file. 

Generates  a  PRN  file  from  a  TS  file. 
Creates  a  Lotus  1-2-3  v2  compatible 
spreadsheet  file  from  a  TS  data  file. 
Generates  a  file  in  a  format  compatible 
with  database  management  programs  from  a 
TS  data  file. 

Creates  a  dBASE  III+  compatible  database 
file  from  a  TS  data  file. 

A  utility  for  viewing  and  creating  tables 
and  new  TS  files  from  existing  TS  files. 
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All  of  these  conversion  utilities,  except  TSTABLES.EXE,  take  in 
filenames  as  parameters  and  process  all  of  the  data  in  those 
files.  That  is,  running  TS2DBF  upon  a  CORN.TS  file  will  produce 
a  DBF  database  file  containing  all  of  the  data  in  the  CORN.TS 
file  and  not  a  subset.  If  a  subset  is  desired,  you  can  use  the 
Table/Create  Tables  choice  in  the  main  TS  program  (TS.EXE). 

PRN2TS.EXE 

The  utility  for  converting  electronic  data  tables  into  TS  data 
files  is  PRN2TS .  It  is  a  batch  program  and  uses  two  files:  an 
ASCII  file  that  contains  the  data  to  be  converted  ( . PRN  extension 
by  default) ,  and  an  ASCII  configuration  file  with  a  .MNU 
extension  that  contains  instructions  on  the  data  organization  and 
menu  headings  (fig.  18) .  Both  files  must  have  the  same  name  as 
the  TS  file  that  is  to  be  created.  For  example,  to  create  a 
WHEAT. TS  file,  the  PRN2TS  program  would  need  a  WHEAT. PRN  file  and 
a  WHEAT. MNU  file. 

The  ASCII  data  file  must  be  organized  with  years  in  the  first 
column  or  first  row  of  each  table.2  All  data  tables  must  be  the 
same  size  with  the  same  number  of  rows  and  columns,  forming  equal 
sized  "blocks."  Rows  and  columns  must  be  in  the  same  order 
within  each  of  the  blocks  and  all  cells  must  contain  a  numeric 
value.  If  an  entire  series  is  zero  or  missing  for  one  or  a  few 
of  the  blocks  but  present  in  other  blocks,  zeros  or  some  number 
must  be  entered  for  the  series. 

Figure  18  shows  how  the  information  in  the  .PRN  and  .MNU  files 
are  linked  for  a  simple  data  file  with  6  data  tables  and  14 
columns  with  the  years  down  the  first  column.  You  can  build  much 
larger  files.  ERS  uses  TS  data  files  with  over  190  country 
tables,  each  containing  16  columns  of  variables  and  over  30  rows 
of  annual  data.  The  current  PRN2TS  program  allows  you  to  create 
a  TS  data  file  with  up  to  500  tables  and  100  years  and  columns. 
Once  you  have  a  .PRN  file  and  a  .MNU  file  that  correspond,  you 
can  create  a  TS  data  file  by  typing: 

PRN2TS  FILENAME. PRN 

where  FILENAME. PRN  is  the  name  of  the  ASCII  data  file. 

Remember,  the  name  of  the  new  TS  data  file  will  correspond  with 
the  name  given  the  two  source  files  (that  is,  a  WHEAT. PRN  data 
file  and  a  WHEAT. MNU  instruction  file  will  create  a  WHEAT. TS 
file) .  If  you  have  followed  all  the  steps  properly,  the  PRN2TS 
program  soon  will  create  a  new  TS  file.  If  you  have  neglected  an 


^Years  may  be  arrayed  across  the  top  row,  but  if  the  time  series  is  very 
long — say,  40  years  of  entries  with  6  or  more  digits--the  width  of  the  .PRN  file 
may  exceed  240  characters.  Although  this  presents  no  problems  for  the  PRN2TS 
program,  it  is  often  a  limitation  for  the  spreadsheet  or  ASCII  editor  programs 
used  to  generate  the  .PRN  file. 
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Figure  18.  MNU  file  information  must  correspond  with  the  PRN  file 
.PRIM  data  file  _ .MNU  file 
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PRN2TS.EXE  - ►  .TS  data  file 


item  or  have  failed  to  get  the  proper  correspondence  between  the 
PRN  data  file  and  the  MNU  configuration  file,  one  of  two  types  of 
errors  will  occur.  You  may  receive  an  error  message  and  the  TS 
file  will  not  be  created.  This  will  happen  if  you  have  failed  to 
specify  the  correct  number  of  blocks  or  columns. 

The  second  type  of  error  occurs  when  the  PRN2TS  program  creates  a 
TS  file  but  the  table  or  menu  headings  are  mislabeled.  This  can 
happen  when  the  labels  and  parameters  in  the  MNU  file  do  not 
correspond  with  the  PRN  file.  These  errors  are  more  difficult  to 
catch.  You  should  carefully  check  the  data  in  the  new  TS  file 
against  the  original  source. 

One  of  the  easiest  ways  to  create  a  PRN  file  is  to  first  assemble 
and  organize  the  data  in  a  spreadsheet  file  with  the  regular 
block  and  column  configuration  explained  above.  Then  export  the 
data  to  a  text  or  PRN  file.  If  the  PRN  file  requires  further 
editing,  use  a  DOS  text  editor  such  as  PROGRAM  EDITOR  from 
WordPerfect  Corp.3 

The  MNU  file  can  be  created  by  typing  the  instructions  in  a  text 
file  following  the  format  in  figure  18.  The  PRN2TS  program  reads 
only  the  first  25  characters  in  each  line,  so  it  is  not  necessary 
to  type  in  the  line  prompts  for  the  MNU  file.  The  easiest  way  to 
create  an  MNU  file  is  to  edit  an  existing  one.  If  one  does  not 
exist,  you  can  create  an  MNU  file  called  BASIC_TS.MNU  by  typing 
PRN2TS  /SAMPLE. 

WKS2PRN.EXE 

The  WKS2PRN  utility  helps  start  the  process  of  generating  a  TS 
data  file  from  data  kept  in  a  spreadsheet  WK1  or  WKS  file.  By 
running  WKS2PRN  FILENAME. WK1 ,  all  of  the  values  and  labels  in 
FILENAME. WK1  will  be  saved  to  FILENAME . PRN .  You  can  then  edit 
this  file  and  a  matching  FILENAME. MNU  file  before  using  the 
PRN2TS  utility. 

TS2PRN.EXE  and  TS2MNU.EXE 

TS2PRN  and  TS2MNU  will  generate  the  PRN  and  MNU  text  files, 
respectively,  for  an  existing  TS  file.  Both  programs  are  very 
simple  to  run.  For  the  TS2MNU  program,  for  example,  type  TS2MNU 
FILENAME. TS.  These  programs  can  be  useful  if  you  have  an 
existing  TS  file  that  conforms  more  closely  to  the  format  of  the 
file  you  wish  to  create  than  does  the  generic  BASIC_TS.MNU  output 
of  the  PRN2TS  program.4 


3If  some  or  all  of  the  data  you  wish  to  assemble  are  already  in  one  or  more 
existing  TS  data  files,  the  task  of  creating  a  new  TS  file  is  easier.  See  the 
section,  "Multiple-File  Utilities." 

4You  can  also  use  the  Create  Tables  capability  of  the  TSTABLES  utility  to 
write  a  new  TS  file  and  the  associated  MNU  file  for  a  subset  of  the  data  in  an 
existing  TS  file. 
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TSTABLES.EXE  and  READ.EXE 


Two  utility  programs  -  TSTABLES  and  READ  -  will  help  you  check  a 
newly  created  TS  file  against  the  . PRN  and  . MNU  files  used  in  its 
creation.  TSTABLES  permits  you  to  view  and  create  tables  of  TS 
files.  These  are  features  of  the  TIME  SERIES  program  itself,  but 
tabular  functions  are  easier  to  access  through  the  TSTABLES 
program.  Just  type  TSTABLES  and  you  will  see  an  opening  menu 
like  the  one  in  figure  19. 


Select  "Load  a  TS  File" 
to  get  a  menu  of  the  TS 
data  files  available 
and  then  select  the  TS 
data  file  you  wish  to 
view  from  a  menu  of 
files  available.  Once 
a  TS  data  file  is 
loaded,  you  can  go  to 
the  Browse  Tables  menu 
choice  to  examine  the 
data. 

You  can  quickly  check 
your  .PRN  and  .MNU 
source  files  for  the 
source  of  the  problem 
with  the  READ.EXE 
program  if  you  do  find 
an  error.  Just  type 
READ  FILENAME . TXT . 


Figure  19 .  TSTABLES  opening  menu  with 
data  file  choices 


I—  TS  Tables 
Load  a  TS  File 
Browse  Tables 
Create  Tables 
Units 
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E:sTS\UTIL\DATA\*.TS 


<PARD1T> 

6/67/98 

ec$inprt.ts 

2/24/89 

srseed .ts 

3/29/96 

187 sugar .ts 

6/65/96 

ecpr ices.ts 

1/23/98 

ssh3.ts 

3/23/98 

argpse.ts 

2/21/96 

exintr.ts 

1/18/98 

ssbrssf .ts 

3/29/98 

barleyl.ts 

2/68/96 

jpnwdat . ts 

4/18/98 

ssseed.ts 

3/29/98 

blprts.ts 

11/63/89 

prcproun.ts 

2/23/96 

sunseed.ts 

3/29/96 

Canada. ts 

2/61/96 

prrice.ts 

4/93/96 

swh3.ts 

3/22/96 

canpse.ts 

2/21/96 

rapeseed.ts 

3/29/96 

udcgwhsb.ts 

4/38/90 

cgcon.ts 

3/38/96 

rice.ts 

4/63/96 

wheat .ts 

1/19/98 

coarsegr  .ts 

2/22/98 

scg3.ts 

3/22/96 

wheats. ts 

6/88/98 

ec$exprt .ts 

2/24/89 

scguh.ts 

3/26/96 

Choose  a  TIHE  SEBIES  file.  Current  file  is  :  NONE 


READ.EXE  does  not  allow 

you  to  edit  files  but  you  can  scroll  up  and  down  and  left  and 
right  to  see  if  you  can  identify  the  source  of  the  error  before 
using  a  text  editor  to  correct  the  error. 


TS2WK1.EXE 


The  TS2WK1  utility  creates  a  Lotus  1-2-3  v2  spreadsheet- 
compatible  WK1  data  file  from  the  entire  data  contents  of  a  TS 
file.  Type  TS2WK1  for  information  on  its  use.  Caution:  WK1 
files  are  about  four  times  the  size  of  TS  files,  so  you  will  need 
plenty  of  available  disk  space  to  create  WK1  files  from  large  TS 
data  files.  If  you  want  to  export  a  subset  of  a  TS  file  to  a  WK1 
file,  use  the  Create  Tables/ Export/ Save  choice  in  the  main  TS 
program. 

TS2DBASE.EXE 

The  TS2DBASE  utility  uses  a  TS  data  file  to  generate  a  file 
format  compatible  with  commercial  database  programs.  It  works 
like  the  TS2MNU  and  TS2PRN  utilities.  That  is,  you  type  TS2DBASE 
FILENAME. TS  and  the  program  will  generate  a  database-compatible 
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file  of  the  same  name  with  a  CSV  (comma  separated  value) 
extension.  You  may  use  DOS  wildcards  to  generate  a  number  of  CSV 
files  from  TS  files  at  one  time.  (Type  TS2DBASE  *.*,  for 
example,  to  generate  CSV  files  for  all  the  TS  files  in  a 
subdirectory) .  Because  many  common  data  operations  are  easier  in 
TS  than  in  commercial  database  packages,  you  may  wish  to  use  the 
TS  utilities  to  perform  any  desired  reconfiguration  of  the  data 
in  TIME  SERIES  prior  to  converting  a  TS  file  to  a  database- 
compatible  file. 

TS2DBF.EXE 


The  TS2DBF  utility  creates  a  dBASE  III+  database-compatible  DBF 
data  file  from  the  entire  data  contents  of  a  TS  file.  Type 
TS2DBF  for  information  on  its  use.  If  you  want  to  export  a 
subset  of  a  TS  file  to  a  DBF  file,  use  the  Create  Tables/Export/ 
Save  choice  in  the  main  TS  program. 

Single-File  Utilities 

The  major  difference  between  TIME  SERIES  and  its  derivative 
program  PS&D  VIEW  is  that  the  former  provides  not  only  a  means  of 
quickly  looking  at  and  analyzing  times  series  data,  it  also 
includes  a  set  of  utilities  for  carrying  out  standard 
manipulations  of  the  data.  PS&D  VIEW  is  a  look-but-don ' t-touch 
program.  It  is  designed  to  allow  users  within  and  outside  USDA 
to  view  tables,  graphs,  and  time  trends  of  official  USDA  supply- 
utilization  data  without  allowing  any  changes  to  the  historical 
numbers  in  the  data  files  that  the  program  displays.  Users  can 
export  the  data  from  PS&D  VIEW  for  use  in  other  programs  using 
the  Create  Table  option,  but  they  cannot  change  the  data  the 
program  displays. 

The  open  framework  of  TIME  SERIES  allows  users  to  tailor  data 
files  to  fit  their  individual  needs.  The  diversity  of  needs  has 
led  to  demands  for  utility  programs  to  facilitate  the  creation  of 
new  TS  data  files  from  existing  TS  data  files.  All  the  functions 
of  these  utilities  could  be  performed  by  first  doing  the  data 
manipulations  in  commercial  database  or  spreadsheet  programs, 
then  creating  new  PRN  and  MNU  files  and  using  the  PRN2TS.EXE 
program  to  build  a  new  TS  data  file.  In  many  cases,  however, 
users  merely  want  a  modification  of  a  file  that  already  exists. 

Modifications  to  an  existing  TS  data  file  can  be  made  using 
several  different  TS  utilities  (table  3) .  The  menu  shell  program 
TSSHELL  will  facilitate  the  selection  and  use  of  these  and  other 
TS  utilities.  All  are  at  different  stages  of  development  and  all 
are  likely  to  be  revised  based  on  feedback  from  users.  The 
emphasis  in  building  these  utilities  was  to  give  users  a  program 
that  would  work  and  address  an  immediate  need.  Refinements  will 
be  developed  with  broader  use. 
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Table  3 —  Single-file  utilities 


File  name 

Description  of  function 

TSBLOCK.EXE^ 

Creates  a  new  block  of  data  from  a 
combination  of  existing  blocks  in  a  file 
and  appends  it  to  the  end  of  the  file. 

TSADD.EXE  and 
TSSUB.EXE 

Batch  versions  of  the  TSBLOCK  utility  for 
adding  or  subtracting  data  blocks. 

TSCOLUMN . EXE- 

Computes  a  new  column  from  two  existing 
columns  and  appends  it  to  the  right  of 
the  last  column  in  the  TS  file. 

TSSUBSET.EXE 
* . BSS ,  *.CSS 

Copies  a  subset  of  blocks  (tables)  or 
columns  to  a  new  file.  For  a  block 
subset,  use  a  configuration  file  with  the 
BSS  extension;  for  a  column  subset,  use  a 
configuration  file  with  the  CSS 
extension. 

ADDYEARS . EXE 

Adds  year  rows  at  the  bottom  of  tables  in 
a  TS  file  so  that  projections  can  be 
saved  to  the  file. 

TSEDIT.EXE^ 

A  utility  which  allows  the  user  to  edit 
the  data  stored  in  a  TS  file. 

TSUPDATE . EXE~ 

Performs  the  same  function  as  TSEDIT 
except  the  data  is  presented  by  year  to 
facilitate  updating. 

TSADJYR.EXE 

Multiplies  file  values  by  a  vector  of 
annual  values.  Useful  for  exchange  rate 
conversions  and  for  deflating  prices. 

TSSCALAR.EXE 

Multiplies  one  or  more  columns  in  a  file 
by  a  scalar.  It  is  useful  for  converting 
units  (metric  tons  to  bushels,  for 
example) . 

TSTRIM.EXE 

Removes  from  a  TS  file  all  tables, 
columns,  and  year  rows  which  contain  only 
zeros . 

TSBLOCK.EXE 


The  TSBLOCK  utility  creates  a  new  block  (table)  of  data  from  a 
mathematical  combination  of  the  existing  blocks  and  appends  it  to 
the  end  of  the  TS  file.  The  utility  allows  you  only  to  add, 
subtract,  multiply,  or  divide  one  block  by  one  or  more  other 
blocks.  In  mathematical  terms, 

[Block  A]  [Operator (+,-, *  or/)]  [Block  B]  [Operator]  [Block  C] . . . 
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This  utility  is  especially  valuable  for  creating  country 
aggregations  for  supply-utilization  data.  To  use  the  program 
type  TSBLOCK.  The  TSBLOCK  opening  menu  will  give  you  a  list  of 
files  available  in  the  current  directory  from  which  you  can 
choose  the  file  you  need.  Once  you  have  loaded  a  TS  data  file 
into  TSBLOCK,  you  will  be  presented  with  a  pick  list  of  the 
tables  within  the  file  (fig.  20) . 

If  you  want  to  create  a  Rest-of-World  grouping,  for  example,  you 
would  choose  the  World  table  here.  Next,  you  will  be  presented 
with  a  choice  of  operators.  For  the  Rest-of-World  example,  you 
would  choose  here.  Again,  you  will  be  given  a  list  of  the 

tables  in  the  TS  file  with  the  first  table  you  selected  marked 
with  a  .  Choose  one  or  more  of  the  unmarked  tables  using  the 
"  +  "  key.  Press  esc  when  you  have  completed  your  choices.  For 
the  Rest-of-World  example,  you  would  choose  those  countries  that 
you  do  not  want  to  include  in  the  new  Rest-of-World  table  (i.e., 
tables  that  are  to  be  subtracted  from  the  World  table) .  Finally, 
TSBLOCK  will  prompt  you  for  the  name  of  the  new  table.  This  name 
will  appear  on  the  TS  menu  listing  of  table  names  in  the  new  data 
file.  After  the  calculations  are  completed,  you  are  asked  for  a 
name  for  the  new  TS  file.  If  you  choose  the  same  name  as  an 
existing  file,  you  are  given  the  option  to  overwrite  the  existing 
file  or  to  choose  a  new  name. 

Some  thought  should  be  given  to  what  the  TSBLOCK  operation 
implies  for  all  the  columns  within  a  table.  An  arithmetic 
operation  may  make  sense  for  columns  that  are  in  one  type  of 
unit,  but  not  for  others  that  are  in  another  type  of  unit.  The 
TSBLOCK  utility,  however,  carries  out  the  operation  that  you 
specify  on  all  the  columns.  TSBLOCK  handles  the  USDA  PS&D  data 
as  a  special  case,  in  that  yields  are  recalculated  for  the  new 
table . 


Figure  20.  TSBLOCK  screen  with  a  sample  file 

9^.1i.lV  TSBlock  !  Create  New  Blocks  - 
Choose  a  source  filet  C:\TS\BARLEY.TS 
Select  the  first  tablet  WORLD 
Choose  an  operation  (♦-«•/  Esc):  - 

Mark  the  tables  (♦  -)  to  Include,  then  press  <ENTER>t 

"  Data  Blocks  T 

-  WORLD 
FOREIGN 

CENTRALLY  PLANNED 
NEWLY  INDUSTRIALIZING 
LESS  DEVELOPED 

- -  ■ — - - - — -  UNITED  STATES  « 

CANADA  « 

MEXICO 

CARIBBEAN 

CUBA 

ARGENTINA  « 

BRAZIL 

SOUTH  ANERICA  EX.,  BRAZ . 

BOLIVIA 

CHILE 

COLOMBIA 

—  I 
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TSADD.EXE  and  TSSUB.EXE 


The  TSADD  and  TSSUB  batch  utilities  perforin  the  data  addition  and 
subtraction  functions  of  TSBLOCK  (see  above) .  Their  advantage  is 
in  routine  data  management  in  that  a  set  of  data  blocks  to  be 
manipulated  can  be  specified  once  and  then  used  repeatedly.  For 
example,  if  you  would  like  to  create  a  new  regional  aggregate 
using  monthly  updates  of  the  PS&D  data  and  the  list  of  regions  to 
include  is  large,  then  TSADD  or  TSSUB  can  help  automate  the 
process.  Both  utilities  require  a  configuration  file  specifying 
the  name  of  the  new  file  to  create  and  a  list  of  the  data  tables 
to  process.  Type  TSADD  /SAMPLE  or  TSSUB  /SAMPLE  for  a  sample  of 
the  required  configuration  files. 

TSCOLUMN.EXE 

The  TSCOLUMN  utility  performs  arithmetic  operations  on  columns 
within  tables.  Just  as  the  TSBLOCK  utility  performs  the  same 
operation  on  all  columns  of  the  designated  tables,  the  TSCOLUMN 
utility  performs  the  designated  column  operation  on  all  tables. 
Unlike  the  TSBLOCK  program,  however,  only  arithmetic  operations 
between  two  columns  at  a  time  are  permitted.  The  math  operation 
is: 


[Column  X]  [Operation (+, - , *  or  /)]  [Column  Y] 

Suppose,  for  example,  you  had  a  file  of  supply-utilization  data 
for  wheat  and  you  wished  to  compare  the  change  in  stocks  for  all 
countries  in  the  file.  You  would  type  TSCOLUMN  and  respond  to 
the  prompts  presented  to  you,  selecting  Beginning  Stocks  and 
Ending  Stocks  from  a  menu  display  of  the  column  headings,  and 
minus  (-)  as  the  operator.  The  last  two  prompts  ask  for  the  name 
of  the  new  column  you  wish  to  create  and  the  name  of  the  new 
file.  The  new  column  is  appended  to  the  right  of  the  existing 
columns . 

Although  TSCOLUMN  computes  operations  only  between  two  columns  at 
a  time,  it  is  relatively  easy  to  carry  out  a  series  of  two-column 
procedures  to  generate  a  desired  result.  The  computation  of  a 
stock-to-use  ratio,  for  example,  would  first  require  the  addition 
of  feed  use  and  human  food  consumption  to  obtain  total  use  and 
then  a  second  run  of  TSCOLUMN  to  calculate  the  ratio  as  a  final 
step. 

TSSUBSET.EXE 


The  TSSUBSET  program  extracts  or  reorders  either  blocks  (tables) 
or  columns  from  a  source  TS  data  file  to  create  a  new  file.  It 
requires  a  configuration  file  with  a  .BSS  extension  for  handling 
blocks  (tables)  or  a  .CSS  extension  for  handling  columns.  An 
example  will  be  the  easiest  way  to  show  how  the  TSSUBSET  program 
works. 
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Suppose  you  have  a  file  named  WHEAT. TS  containing  wheat  supply- 
utilization  data  with  6  data  blocks  and  14  columns,  such  as  shown 
in  figure  18.  You  could  use  TSSUBSET  to  reorder  the  blocks  and 
delete  the  Foreign  block  by  creating  a  text  file  named  WHEAT. BSS 
with  the  following  information: 

Wheat . ts 
Wheat2 . ts 
1 
6 
2 

3 

4 

The  first  line  refers  to  the  TS  file  to  be  read  and  the  second 
line  is  the  name  to  be  given  to  the  new  file  to  be  created.  The 
listing  of  numbers  tells  the  TSSUBSET  program  to  move  the  last 
block,  labeled  ROW,  up  to  the  second  position  on  the  menu  and 
omit  the  5th  block  labeled  Foreign. 

To  run  the  TSSUBSET  program  for  this  example,  you  would  type: 
TSSUBSET  WHEAT. BSS 

For  this  program,  the  file  extension  is  critical  because  it  tells 
the  TSSUBSET  program  whether  to  run  block  or  column  operations. 
If,  in  this  example,  you  were  to  use  the  .CSS  extension  on  the 
WHEAT  filename,  the  TSSUBSET  program  would  reorder  5  of  the  14 
columns  (fig.  16)  and  omit  the  other  9.  An  easy  way  to  create  a 
BSS  or  CSS  file  for  TSSUBSET  is  to  edit  the  output  of  TS2MNU,  as 
TS2MNU  lists  both  the  table  and  column  names  and  their  order  in 
the  file. 

ADDYEARS.EXE 


ADDYEARS  extends  the  time  period  covered  in  a  data  file  and 
enters  zeros  for  all  the  new  values.  By  adding  space  for 
additional  years,  this  utility  makes  it  possible  to  use  the  two 
edit  utilities,  TSEDIT  and  TSUPDATE  to  insert  new  data  at  the  end 
of  the  time  series  or  to  save  projections  to  the  file.  Another 
use  of  ADDYEARS  is  to  make  files  containing  different  annual  time 
series  compatible  so  they  can  be  manipulated  with  utilities  such 
as  TSCOPY  and  TSJOIN  described  below. 

To  use  ADDYEARS,  type: 

ADDYEARS  FILENAME. TS  YEARS 

For  example,  ADDYEARS  WHEAT. TS  5  will  add  entries  for  5  more 
years  to  each  of  the  tables  in  the  WHEAT  data  file.  You  may  use 
DOS  wildcards  with  the  ADDYEARS  utility.  For  example,  you  could 
type  ADDYEARS  *.*  7  and  space  for  7  years  of  data  will  be  added 
to  all  the  TS  data  files  in  the  directory. 
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TSEDIT.EXE  and  TSUPDATE.EXE 


You  can  edit  individual  data  entries  in  a  TS  file  with  either 
TSEDIT  or  TSUPDATE.  The  difference  between  the  two  is  that 
TSEDIT  displays  data  for  editing  in  a  time  series  column  on  the 
screen  while  TSUPDATE  displays  rows  of  data  for  a  given  year  on 
the  screen.  Type  TSEDIT  FILENAME. TS  to  edit  the  data  in 
FILENAME.  CAUTION:  Any  edits  you  make  to  the  data  are  saved 
immediately  to  the  disk,  so  make  a  back-up  copy  of  your  TS  file 
before  starting. 

TSADJYR.EXE 


TSADJYR  (TS  Adjust  Year)  multiplies  or  divides  all  the  columns  in 
a  TS  data  file  by  a  time  series  vector  of  constants,  as 
illustrated  in  figure  21.  Its  most  common  use  is  to  convert  data 
from  nominal  to  constant  values  using  an  index  of  annual  price 
changes,  such  as  the  GNP  deflator.  Another  obvious  application 
would  be  to  convert  data  from  one  currency  to  another.  The 
source  file  name,  the  new  file  name,  the  mathematical  operation 
(/  or  *) ,  and  the  vector  of  constants  must  be  specified  in  a 
configuration  text  file  constructed  by  the  user.  The 
configuration  file  can  have  any  name  and  extension  specified  by 
the  user,  because  TSADJYR  reads  the  configuration  file  to  pick  up 
the  names  of  the  TS  files  to  read  and  create.  The  syntax  for 
implementing  the  utility  is: 

TSADJYR  FILENAME . TXT 

To  obtain  a  sample  configuration  file  that  can  then  be  edited, 
type  TSADJYR  /SAMPLE. 

TSSCALAR.EXE 


The  TSSCALAR  utility  multiplies  an  entire  column  by  a  single 
number  or  scalar.  You  can  use  it  for  converting  from  one  set  of 
units  to  another,  such  as  from  bushels  to  metric  tons.  TSSCALAR 
functions  are  similar  to  the  Program/ Scalar  choice  in  the  TS 
program  menu  except  for  two  important  differences.  First,  the 
TSSCALAR  utility  allows  you  to  specify  which  columns  are  to  be 
multiplied  by  the  user-specified  scalar.  In  the  TS  program,  the 
Scalar  option  changes  all  the  values  displayed  from  the  file. 
Second,  the  TSSCALAR  utility  writes  the  new  values  to  the  file 
you  specify.  In  the  TS  program,  only  the  display  values  are 
changed,  not  the  original  data. 

The  syntax  for  TSSCALAR  is  the  same  as  for  TSADJYR.  The  user 
must  specify  the  source  file,  the  new  file  name,  and  list  the 
scalars  which  are  to  be  multiplied  by  each  column  in  a 
configuration  file.  The  configuration  file  can  have  any  name  you 
choose.  The  list  of  scalars  included  in  the  configuration  file, 
however,  must  match  the  order  of  the  columns  in  the  source  file. 
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Figure  21.  TSADJYR  can  be  used  to  deflate  data  series 

USEX.TS  DEFLATE.TXT  NEWUSEX.TS 

U.S.  Exports 

U  S-  Exports  Deflator  (Mil.  Constant  $) 


t 
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The  first  column  -  that  is,  the  column  with  the  year  identifier 
in  it  -  is  multiplied  by  1.  Any  column  which  is  not  being 
changed  must  also  be  multiplied  by  1.  As  with  the  TSDAJYR 
utility,  you  can  obtain  a  sample  configuration  file  (which  you 
can  then  edit)  by  typing  TS SC ALAR  /SAMPLE. 

TSTRIM.EXE 


TSTRIM  was  designed  to  reduce  the  size  of  TS  data  files  that  are 
used  frequently,  particularly  the  supply-utilization  files.  It 
removes  any  tables,  columns,  or  years  in  a  TS  data  file  that  are 
all  zeros.  The  syntax  for  the  TSTRIM  utility  is: 

TSTRIM  basefile  outputfile 

or,  for  example,  TSTRIM  rice.ts  newrice . ts . 

Although  TSTRIM  is  a  great  disk  space  saver,  it  may  change  the 
structure  of  a  file  so  as  to  make  it  incompatible  with  other 
files.  For  example,  TSTRIM  would  remove  the  Brazil  block  in  a 
RAPESEED . TS  file  because  Brazil  does  not  produce  or  trade 
rapeseed.  This  is  not  a  problem  if  you  want  to  examine  only  the 
world  rapeseed  market.  If,  however,  you  want  to  focus  on  the 
world  oilseed  market,  you  could  not  use  the  TSFILE  utility  to 
aggregate  the  "trimmed"  rapeseed. ts  file  and  a  soybeans. ts  file 
because  the  table  structure  of  the  two  files  would  not  be  the 
same  (that  is,  country  lists  would  differ) . 

The  compromise  of  building  a  database  with  a  consistent  structure 
that  is  amenable  to  manipulation  is  that  zeros  must  be  maintained 
in  places  where  data  are  not  relevant.  The  result  is  that  the 
size  of  a  file  needs  to  be  greater  than  its  information  content 
would  warrant  in  order  to  build  software  applications  that  make 
data  manipulations  easy  and  flexible.  The  TSTRIM  utility  makes 
the  size  of  a  TS  data  file  more  consistent  with  its  information 
content  but  may  sacrifice  its  compatibility  with  other  files  in 
the  database. 

Multiple-File  Utilities 

It  is  often  useful  to  merge  the  data  kept  in  two  or  more  TS  files 
into  a  single  TS  file  for  viewing  and  use.  Table  4  lists  a 
developing  group  of  utilities  available  to  perform  the  more 
common  of  these  tasks. 

TSCOPY.EXE 


The  TSCOPY  program  allows  you  to  create  a  new  file  by  copying  the 
same  table  out  of  a  series  of  existing  TS  data  files.  Thus,  the 
TSCOPY  program  can  be  used  to  convert  commodity  TS  files  with 
country  tables  into  country  TS  files  with  commodity  tables.  For 
example,  the  United  States  table  could  be  copied  from  each  of 
several  commodity  files  to  create  a  United  States  data  file  for 
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Table  4 —  Multiple-file  utilities 


File  name  Description  of  function 


TSCOPY.EXE 
*  .  CPY 


TSCOPYNM.EXE 
*  .  CPY 


TSCOPYC.EXE 
*  .  CPY 


TSJOIN.EXE 


TSFILE.EXE 


Creates  a  new  TS  file  by  copying  the  same 
table  number  from  a  series  of  existing  TS 
files.  The  utility  uses  a  configuration  file 
with  the  .CPY  extension. 

Creates  a  new  TS  file  by  copying  the  same 
table  (based  on  name)  from  a  series  of  TS 
files.  The  resulting  file  has  column  names 
and  year  coverage  encompassing  the  ranges  of 
the  TS  files. 

Creates  a  new  TS  file  by  copying  the  same 
column  of  data  from  several  TS  files. 

Creates  a  new  TS  file  by  copying  a  user- 
specified  column  of  data  from  a  source  TS  file 
and  joining  it  to  a  host  TS  file. 

Aggregates  two  files  with  the  same  column  and 
block  structure. 


cross-commodity  comparisons.  In  its  present  form,  the  program  is 
restricted  to  use  with  a  large  well-organized  uniform  set  of  TS 
data  files.  All  the  source  TS  files  must  have  the  same  table 
sequence  and  structure.  You  must  designate  the  location  of  the 
table  to  be  copied  and  the  TS  files  to  use  in  a  configuration 
file  with  a  .CPY  extension.  Figure  22  shows  graphically  how 
TSCOPY  works  and  shows  how  the  .CPY  configuration  file 
information  is  used  to  generate  the  result. 

TSCOPYNM.EXE 

TSCOPYNM  is  a  variation  of  TSCOPY.  It  also  copies  the  same  table 
out  of  a  series  of  TS  files,  but  TSCOPYNM  locates  the  tables 
based  upon  name  -  not  table  number.  It  is  also  more  flexible  in 
handling  files  with  different  year  coverage  and  different  column 
names.  Use  TSCOPYNM  in  place  of  TSCOPY,  unless  you  must  fix  the 
number  and  names  of  columns  to  those  of  the  first  TS  file  listed 
in  the  CPY  file.  Type  TSCOPYNM  /SAMPLE  for  a  sample  CPY  file. 
TSCOPYNM  is  the  easiest  way  to  create  a  country  file  from  a  mix 
of  supply-use  commodity  files. 

TSCOPYC.EXE 


TSCOPYC  works  like  TSCOPY  except  that  it  extracts  data  by  column 
(instead  of  by  table)  from  several  TS  files  for  placement  in  a 
new  TS  file.  You  could  extract  the  Exports  column,  if  present, 
from  a  series  of  commodity  TS  files.  The  result  would  be  an 
EXPORTS. TS  data  file  in  which  the  exports  for  a  number  of 
commodities  would  be  found  in  each  of  the  country  tables.  The 
configuration  file  for  TSCOPYC  has  the  same  extension,  .CPY,  and 
is  virtually  the  same  as  the  configuration  file  for  TSCOPY. 
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Block  2  United  States 


TS JOIN . EXE 


The  TS JOIN  utility  merges  a  column  from  one  TS  data  file  with  the 
data  in  another  file.  For  example,  you  could  merge  population 
data  in  one  TS  file  with  supply-use  data  in  another  TS  file,  as 
shown  in  figure  23.  The  TSCOLUMN  utility  could  then  be  used  to 
compute  a  per  capita  utilization  series.  The  TSJOIN  utility  does 
not  require  that  the  tables  in  both  files  to  be  in  the  same 
order.  A  table  for  China,  for  example,  could  be  the  15th  table  in 
the  population  file  and  table  100  in  the  supply-utilization  file. 
The  table  names,  however,  must  be  spelled  identically  or  TSJOIN 
will  not  be  able  to  match  the  tables  in  the  two  files. 

The  syntax  for  TSJOIN  is: 

TSJOIN  basefile  sourcefile  outputfile  column# 

or,  for  example,  TSJOIN  rice  census  newrice  2 

If  no  match  occurs  for  a  particular  table  in  the  basefile,  the 
table  is  skipped  and  Os  are  entered  for  the  series.  TSJOIN 
reports  the  unsuccessful  matches  in  an  output  file  named 
MISSING . TXT .  You  may  use  the  READ  utility,  or  any  other  ASCII 
text  utility,  to  examine  the  contents  of  the  MISSING.TXT  file. 

TSFILE.EXE 


TSFILE  creates  an  aggregate  or  disaggregate  TS  file  from  two 
existing  TS  files  of  the  same  dimensions  and  structure. 

The  syntax  is: 

TSFILE  Filel  [+-*/]  File2  =  Newfile  /  New  File  Title 

For  example,  you  could  create  a  food  grains  file  from  a  rice  and 
wheat  file  by  typing: 

TSFILE  WHEAT  +  RICE  =  FOODGR  /  Food  Grains 

You  could  also  use  this  utility  to  create  a  net  exports  file  from 
an  exports  and  an  imports  file.  Particular  care  must  be  taken  to 
ensure  that  there  is  a  consistent  table  and  column  structure  for 
both  of  the  source  files.  An  easy  test  of  consistency  is  to 
check  the  size  of  the  two  source  files.  Both  have  to  be  exactly 
the  same  since  space  allocated  for  the  data  in  each  file  will 
have  to  require  the  same  number  of  bytes.  (It  is  possible  for 
two  source  files  to  be  the  same  size  and  have  different 
structures,  but  it  is  very  unlikely.)  If  you  need  further 
verification  of  compatibility  or  need  to  find  how  two  files  are 
different,  compare  the  MNU  files  generated  by  using  the  TS2MNU 
utility  on  the  two  source  files. 
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Figure  23.  TSJOIN  appends  columns  of  data 


CC 


O 
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Compressed  Data  Files 


TS  data  files  with  an  extension  of  .TSC  are  compressed  data  files 
created  by  a  file  compression  utility  such  as  LHARC  or  PKZIP. 

This  compression  is  done  solely  to  conserve  disk  space.  When  you 
select  a  TSC  file  from  the  TS  file  menu,  the  software  opens  the 
file  for  you  and  creates  a  temporary  uncompressed  TS  file  for 
use.  On  faster  modern  PC's,  this  takes  only  a  few  seconds  and 
the  wait  is  well  worth  the  savings  in  disk  space.  However,  there 
are  limits  to  the  use  of  the  TSC  data  files. 

Compressed  TSC  data  files  cannot  be  used  directly  by  any  of  the 
TS  utilities.  TSC  data  files  must  first  be  uncompressed  or 
"opened"  if  you  want  to  use  any  of  the  TS  utilities  with  them. 

To  save  disk  space,  you  can  compress  TS  data  files  which  you 
create.  Some  data  files  will  compress  greatly,  others  will  not. 
Batch  files  to  open  TSC  files  or  to  create  TSC  files  are 
described  here. 

OPEN . BAT  and  OPENALL.BAT 

These  batch  files  will  use  TSC  compressed  data  files  to  create 
extracted  TS  data  files.  OPEN.BAT  works  on  single  files,  one  at 
a  time.  OPENALL.BAT  will  run  OPEN.BAT  for  you  on  all  of  the 
compressed  files  in  the  current  directory. 

Use  these  utilities  if  you  want  to  run  any  of  the  TS  utilities  on 
data  in  a  TSC  file.  Also,  if  opening  the  .TSC  files  in  the  TS 
program  takes  too  long,  then  you  may  want  to  create  faster- 
loading  .TS  files  with  these  utilities. 

Type  OPEN  to  see  a  summary  of  its  use.  Type  OPEN  FILENAME. TSC  to 
create  an  extracted  file.  For  example,  OPEN  WHEAT .TSC  will 
create  the  WHEAT. TS  data  file.  Both  the  OPEN.BAT  file  and  the 
WHEAT. TSC  file  must  be  in  the  current  directory,  and  the  WHEAT. TS 
file  will  be  created  in  the  current  directory. 

The  OPEN.BAT  file  is  a  text  file,  so  you  can  read  it  using  the 
READ.EXE  utility  if  you  are  curious  about  how  it  works. 
Essentially,  it  renames  the  TSC  file  to  a  DOS  executable  name  and 
then  runs  it.  The  OPENALL.BAT  file  is  useful  if  you  decide  to 
use  the  larger  but  faster-loading  TS  files.  Just  type  OPENALL  to 
create  TS  files  for  each  TSC  file.  You  do  not  need  both  TS  and 
TSC  files  of  the  same  data.  Delete  those  you  do  not  need. 
Remember  to  keep  backups  of  files  you  edit  or  manipulate  to 
prevent  unwanted  loss  or  file  overwrites. 

COMPRESS ♦ BAT  and  COMPALL.BAT 


These  batch  files  do  the  opposite  of  OPEN.BAT  and  OPENALL.BAT. 
After  using  the  TS  utilities,  you  can  use  COMPRESS  to  create  a 
compressed  TSC  data  file  if  you  wish  to  save  disk  space. 
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COMPRESS . BAT  works  on  single  files,  one  at  a  time.  COMPALL.BAT 
will  run  COMPRESS  on  all  TS  files  in  the  directory. 

Type  COMPRESS  to  see  a  summary  of  its  use.  Follow  the  word 
COMPRESS  with  the  name  of  the  TS  file  to  compress  to  start  the 
compression  process.  COMPRESS.BAT  will  use  the  LHARC  utility  to 
create  a  .TSC  file  for  you.  For  example,  COMPRESS  WHEAT .TS  will 
create  WHEAT. TSC.  If  you  have  many  TS  files  to  compress,  type 
COMP ALL  to  compress  all  of  them. 

There  are  a  couple  of  considerations  to  keep  in  mind  when  using 
compressed  data  files  in  the  main  TS  program.  TS  will  open  the 
TSC  file  and  create  a  temporary  TS  file.  This  TS  file  is  created 
in  the  same  directory  where  you  start  the  TS  program,  so  some 
disk  space  is  needed  there  for  use.  The  TS  program  checks  for 
this  space  when  the  TSC  file  is  selected.  When  you  are  finished 
viewing  data  from  a  TSC  file  and  either  exit  the  TS  program  or 
select  another  file  from  the  Program/File  menu,  the  temporary  TS 
data  file  is  deleted  and  the  space  it  occupied  is  freed. 

Another  consideration  is  the  possible  loss  of  edits  you  make  to  a 
TS  file  by  opening  a  TSC  file.  Suppose  you  use  the  TS  utilities 
to  manipulate  data  in  a  WHEAT. TS  file.  You  may  also  have  a 
WHEAT. TSC  file  that  contains  a  compressed  version  of  WHEAT. TS. 

If  you  select  WHEAT. TSC  from  the  TS  file  menu,  you  will  be 
notified  that  the  existing  WHEAT. TS  data  will  be  overwritten  if 
you  continue.  You  will  be  given  a  chance  to  stop  and  select 
another  data  file.  To  avoid  the  loss  of  important  data,  store 
different  versions  of  data  files  in  separate  directories  and  keep 
backups . 

If  you  are  using  a  Local  Area  Network  (LAN)  to  house  the  TS 
software  and  data,  you  can  keep  uncompressed  (.TS)  data  files  on 
the  file  server  so  the  workstations  will  not  require  temporary 
disk  space  for  opened  TSC  files.  (Note:  TS  was  not  written  as  a 
LAN-aware  application.  Its  use  on  a  LAN  depends  upon 
configurations  provided  by  your  LAN  administrator  and  functions 
available  in  your  LAN  operating  system  and  environment.) 

Future  Developments 

The  analytical  and  manipulative  power  of  TIME  SERIES  is  dependent 
first  and  foremost  on  the  organization  of  the  data.  This 
organization  makes  it  possible  to  build  software  to  operate  on 
structured  database  files.  We  cannot  emphasize  enough  the 
importance  of  developing  a  coherent  data  structure  which  is  well- 
suited  to  its  intended  application.  Once  you  have  developed  this 
structure,  the  marginal  cost  of  converting  the  data  to  TS  files 
is  relatively  small,  particularly  when  compared  with  the 
analytical  and  manipulative  benefits  of  the  TS  program  and  its 
utilities. 
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The  TIME  SERIES  program  and  utilities  are  only  a  small,  though 
exciting,  part  of  the  work  we  do.  To  the  extent  possible,  we 
will  try  to  respond  to  suggestions  for  further  developments  or 
for  enhancements  in  the  existing  programs.  If  you  have  success 
with  the  TS  utilities  in  developing  your  own  TS  databases,  please 
send  us  a  copy  of  your  TS  data  file(s).  We  maintain  a  user  list 
and  will  inform  you  of  new  software  developments. 

The  long-term  development  objectives  of  the  TIME  SERIES  program 
are  to  reduce  the  costs  of  converting  data  to  TS  files  and  to 
raise  the  benefits  associated  with  using  data  within  the  system. 
This  will  entail  a  number  of  changes  in  the  software  over  the 
next  few  years.  As  in  the  past,  these  changes  will  be  driven  in 
large  measure  by  user  demands.  But  each  new  development  or 
modification  contributes  a  little  more  toward  the  development  of 
a  comprehensive  vision  of  what  a  "finished"  product  should  do  and 
how  it  should  work.  Below  are  some  of  the  changes  being 
contemplated.  User  demands  and  the  difficulty  of  implementing 
them  will  determine  if  they  are  pursued  further. 

■  Combine  all  or  most  of  the  key  utilities  into  an  interactive 
program  with  menus  and  user  prompts.  The  TSSHELL  program  is 
a  beginning  in  this  attempt. 

■  Develop  a  TIME  SERIES  program  that  allows  users  to  compare 
data  series  across  more  than  just  the  three  dimensions 
currently  available  (table,  column,  year) .  This  might  be 
done  by  developing  a  program  that  can  load  more  than  one 
file  at  a  time  or  it  might  entail  a  fundamental  change  in 
the  file  format. 

■  Develop  a  more  flexible  file  format  to  allow  files  to 
contain  tables  of  differing  sizes,  each  with  unique  columns. 

■  Develop  a  means  of  attaching  a  text  note  to  each  data 
series,  with  the  user  able  to  reference  it  with  the  touch  of 
a  key.  As  we  move  into  more  complex  databases  with  multiple 
sources  and  no  single  hardcopy  reference,  this  feature  will 
be  extremely  important. 

■  For  the  file  manipulation  utilities  such  as  TSCOPYC,  and 
TSFILE ,  build  in  the  ability  to  reference  tables  by  name 
rather  than  by  the  position  of  the  table  in  the  file.  This 
capability  already  exists  in  the  TSCOPYNM  and  TSJOIN 
utilities . 

■  Add  versatility  to  the  TSCOLUMN  and  TSBLOCK  utilities  to 
allow  the  use  of  formulas  instead  of  only  single-function 
operations . 

■  Modify  the  TIME  SERIES  programs  and  files  to  allow  viewing 
and  manipulation  of  date-based  observations  (daily,  weekly, 
monthly,  and  quarterly  data) . 
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TS  Utilities  Index 


General  Support  Utilities  -  page  14 

File  name 

Description  of  function 

Page 

TSSHELL.EXE 

A  menu  shell  with  descriptions  and 
syntax  instructions  for  all  of  the  TS 
utilities.  With  TSSHELL,  you  can  scroll 
through  a  list  of  the  TS  utilities  and 
run  the  one  you  want.  This  is  a  good 
entry  point  into  the  suite  of  TS 
software. 

14 

READ . EXE 

A  utility  for  reading  DOS  text  (ASCII) 
files.  This  is  used  by  the  TIME  SERIES 
main  program  and  the  TSTABLES  utility  to 
view  user-created  tables. 

15 

PRINTPCX.EXE 

A  program  to  print  graphs  saved  in  PCX 
format  by  TIME  SERIES. 

15 

TSHELP.EXE 

A  hyper-text  guide  to  the  TS  utilities, 
useful  for  selecting  the  correct  utility 
for  the  task  you  have  in  mind. 

16 

SPECS . EXE  and 
MAP . EXE 

Utilities  to  check  computer  hardware, 
settings,  and  memory  use.  These  are 
useful  for  trouble-shooting. 

16 

DRIVES . EXE 

Lists  the  disk  drives  present  on  the 
computer  and  the  free  space  available  on 
each.  This  is  useful  in  selecting  a 
drive  for  software  and  data 
installation. 

16 

File  Conversion  Utilities  -  page  16 

File  name 

Description  of  function 

Page 

PRN2TS.EXE 
* . PRN / * . MNU 

Creates  a  TS  binary  file  from  data  in  an 
ASCII  text  (PRN)  file.  The  utility  uses 
a  text  configuration  file  with  a  MNU 
extension  for  instructions. 

18 

WKS2PRN.EXE 

Dumps  the  labels  and  values  in  a 
spreadsheet  file  to  a  text  file. 

20 

TS2MNU.EXE 

Creates  the  MNU  configuration  file  for 
an  existing  TS  file. 

20 

TS2PRN.EXE 

Generates  a  PRN  file  from  a  TS  file. 

20 
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File  Conversion  Utilities  -  page  16 

File  name 

Description  of  function 

Page 

TSTABLES.EXE 

A  utility  for  viewing  and  creating 
tables  and  new  TS  files  from  existing  TS 
files . 

21 

TS2WK1.EXE 

Creates  a  Lotus  1-2-3  v2  compatible 
spreadsheet  file  from  a  TS  data  file. 

21 

TS2DBASE.EXE 

Generates  a  file  in  a  format  compatible 
with  database  management  programs  from  a 
TS  data  file. 

21 

TS2DBF.EXE 

Creates  a  dBASE  III+  compatible  database 
file  from  a  TS  data  file. 

22 

OPEN . BAT 
OPENALL.BAT 

Creates  TS  data  files  from  TSC 
compressed  data  files. 

34 

COMPRESS . BAT 
COMP ALL . BAT 

Creates  compressed  TSC  data  files  from 

TS  data  files. 

34 

Single-File  Utilities  -  page  22 

File  name 

Description  of  function 

Page 

TSBLOCK.EXE 

Creates  a  new  block  of  data  from  a 
combination  of  existing  blocks  in  a  file 
and  appends  it  to  the  end  of  the  file. 

23 

TSADD.EXE  and 
TSSUB.EXE 

Batch  versions  of  the  TSBLOCK  utility 
for  adding  or  subtracting  data  blocks. 

25 

TSCOLUMN.EXE 

Computes  a  new  column  from  two  existing 
columns  and  appends  it  to  the  right  of 
the  last  column  in  the  TS  file. 

25 

TSSUBSET.EXE 
* . BSS ,  *.CSS 

Copies  a  subset  of  blocks  (tables)  or 
columns.  For  a  block  subset,  use  a 
configuration  file  with  the  BSS 
extension;  for  a  column  subset,  use  a 
configuration  file  with  the  CSS 
extension. 

25 

ADDYEARS.EXE 

Adds  year  rows  at  the  bottom  of  tables 
in  a  TS  file  so  that  projections  can  be 
saved  to  the  file. 

26 

TSEDIT.EXE 

A  utility  which  allows  the  user  to  edit 
the  data  stored  in  a  TS  file. 

27 
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Single-File  Utilities  -  page  22 

File  name 

Description  of  function 

Page 

TSUPDATE.EXE 

Performs  the  same  function  as  TSEDIT 
except  the  data  is  presented  by  year  to 
facilitate  updating. 

27 

TSADJYR.EXE 

Multiplies  file  values  by  a  vector  of 
annual  values.  Useful  for  exchange  rate 
conversions  and  for  deflating  prices. 

27 

TSSCALAR.EXE 

Multiplies  one  or  more  columns  in  a  file 
by  a  scalar.  It  is  useful  for 
converting  units  (metric  tons  to 
bushels,  for  example) . 

27 

TSTRIM.EXE 

Removes  from  a  TS  file  all  tables, 
columns,  and  year  rows  which  contain 
only  zeros. 

29 

Multiple-File  Utilities  -  page  29 

File  name 

Description  of  function 

Page 

TSCOPY.EXE 
* .  CPY 

Creates  a  new  TS  file  by  copying  the 
same  table  number  from  a  series  of 
existing  TS  files.  The  utility  uses  a 
configuration  file  with  the  .CPY 
extension. 

29 

TSCOPYNM.EXE 
*  .  CPY 

Creates  a  new  TS  file  by  copying  the 
same  table  (based  on  name)  from  a  series 
of  TS  files.  The  resulting  file  has 
column  names  and  year  coverage 
encompassing  the  ranges  of  the  TS  files. 

30 

TSCOPYC.EXE 
*  .  CPY 

Creates  a  new  TS  file  by  copying  the 
same  column  of  data  from  several  TS 
files. 

30 

TSJOIN.EXE 

Creates  a  new  TS  file  by  copying  a  user- 
specified  column  of  data  from  a  source 

TS  file  and  joining  it  to  a  host  TS 
file. 

32 

TSFILE.EXE 

Aggregates  two  files  with  the  same 
column  and  block  structure. 

32 
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